home *** CD-ROM | disk | FTP | other *** search
/ SGI Freeware 1999 August / SGI Freeware 1999 August.iso / dist / fw_perl.idb / usr / freeware / catman / p_man / cat3 / CGI::Carp.Z / CGI::Carp
Encoding:
Text File  |  1998-10-28  |  8.2 KB  |  265 lines
  1.  
  2.  
  3.  
  4.      CCCCGGGGIIII::::::::CCCCaaaarrrrpppp((((3333))))    22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))      CCCCGGGGIIII::::::::CCCCaaaarrrrpppp((((3333))))
  5.  
  6.  
  7.  
  8.      NNNNAAAAMMMMEEEE
  9.       CCCCGGGGIIII::::::::CCCCaaaarrrrpppp - CGI routines for writing to the HTTPD (or    other)
  10.       error    log
  11.  
  12.      SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  13.           use CGI::Carp;
  14.  
  15.           croak "We're outta here!";
  16.           confess "It was my fault:    $!";
  17.           carp "It was your    fault!";
  18.           warn "I'm    confused";
  19.           die  "I'm    dying.\n";
  20.  
  21.  
  22.      DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  23.       CGI scripts have a nasty habit of leaving warning messages
  24.       in the error logs that are neither time stamped nor fully
  25.       identified.  Tracking    down the script    that caused the    error
  26.       is a pain.  This fixes that.    Replace    the usual
  27.  
  28.           use Carp;
  29.  
  30.       with
  31.  
  32.           use CGI::Carp
  33.  
  34.       And the standard _w_a_r_n(), die (), _c_r_o_a_k(), _c_o_n_f_e_s_s() and
  35.       _c_a_r_p() calls will automagically be replaced with functions
  36.       that write out nicely    time-stamped messages to the HTTP
  37.       server error log.
  38.  
  39.       For example:
  40.  
  41.          [Fri Nov 17 21:40:43 1995]    test.pl: I'm confused at test.pl line 3.
  42.          [Fri Nov 17 21:40:43 1995]    test.pl: Got an    error message: Permission denied.
  43.          [Fri Nov 17 21:40:43 1995]    test.pl: I'm dying.
  44.  
  45.  
  46.      RRRREEEEDDDDIIIIRRRREEEECCCCTTTTIIIINNNNGGGG EEEERRRRRRRROOOORRRR MMMMEEEESSSSSSSSAAAAGGGGEEEESSSS
  47.       By default, error messages are sent to STDERR.  Most HTTPD
  48.       servers direct STDERR    to the server's    error log.  Some
  49.       applications may wish    to keep    private    error logs, distinct
  50.       from the server's error log, or they may wish    to direct
  51.       error    messages to STDOUT so that the browser will receive
  52.       them.
  53.  
  54.       The carpout()    function is provided for this purpose.    Since
  55.       _c_a_r_p_o_u_t() is not exported by default,    you must import    it
  56.       explicitly by    saying
  57.  
  58.          use CGI::Carp qw(carpout);
  59.  
  60.  
  61.  
  62.  
  63.      Page 1                        (printed 10/23/98)
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.      CCCCGGGGIIII::::::::CCCCaaaarrrrpppp((((3333))))    22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))      CCCCGGGGIIII::::::::CCCCaaaarrrrpppp((((3333))))
  71.  
  72.  
  73.  
  74.       The _c_a_r_p_o_u_t()    function requires one argument,    which should
  75.       be a reference to an open filehandle for writing errors.  It
  76.       should be called in a    BEGIN block at the top of the CGI
  77.       application so that compiler errors will be caught.
  78.       Example:
  79.  
  80.          BEGIN {
  81.            use CGI::Carp qw(carpout);
  82.            open(LOG, ">>/usr/local/cgi-logs/mycgi-log") or
  83.          die("Unable to    open mycgi-log:    $!\n");
  84.            carpout(LOG);
  85.          }
  86.  
  87.       _c_a_r_p_o_u_t() does not handle file locking on the    log for    you at
  88.       this point.
  89.  
  90.       The real STDERR is not closed    -- it is moved to SAVEERR.
  91.       Some servers,    when dealing with CGI scripts, close their
  92.       connection to    the browser when the script closes STDOUT and
  93.       STDERR.  SAVEERR is used to prevent this from    happening
  94.       prematurely.
  95.  
  96.       You can pass filehandles to _c_a_r_p_o_u_t()    in a variety of    ways.
  97.       The "correct"    way according to Tom Christiansen is to    pass a
  98.       reference to a filehandle GLOB:
  99.  
  100.           carpout(\*LOG);
  101.  
  102.       This looks weird to mere mortals however, so the following
  103.       syntaxes are accepted    as well:
  104.  
  105.           carpout(LOG);
  106.           carpout(main::LOG);
  107.           carpout(main'LOG);
  108.           carpout(\LOG);
  109.           carpout(\'main::LOG');
  110.  
  111.           ... and so on
  112.  
  113.       FileHandle and other objects work as well.
  114.  
  115.       Use of _c_a_r_p_o_u_t() is not great    for performance, so it is
  116.       recommended for debugging purposes or    for moderate-use
  117.       applications.     A future version of this module may delay
  118.       redirecting STDERR until one of the CGI::Carp    methods    is
  119.       called to prevent the    performance hit.
  120.  
  121.      MMMMAAAAKKKKIIIINNNNGGGG PPPPEEEERRRRLLLL EEEERRRRRRRROOOORRRRSSSS    AAAAPPPPPPPPEEEEAAAARRRR IIIINNNN TTTTHHHHEEEE BBBBRRRROOOOWWWWSSSSEEEERRRR WWWWIIIINNNNDDDDOOOOWWWW
  122.       If you want to send fatal (die, confess) errors to the
  123.       browser, ask to import the special "fatalsToBrowser"
  124.       subroutine:
  125.  
  126.  
  127.  
  128.  
  129.      Page 2                        (printed 10/23/98)
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.      CCCCGGGGIIII::::::::CCCCaaaarrrrpppp((((3333))))    22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))      CCCCGGGGIIII::::::::CCCCaaaarrrrpppp((((3333))))
  137.  
  138.  
  139.  
  140.           use CGI::Carp qw(fatalsToBrowser);
  141.           die "Bad error here";
  142.  
  143.       Fatal    errors will now    be echoed to the browser as well as to
  144.       the log.  CGI::Carp arranges to send a minimal HTTP header
  145.       to the browser so that even errors that occur    in the early
  146.       compile phase    will be    seen.  Nonfatal    errors will still be
  147.       directed to the log file only    (unless    redirected with
  148.       carpout).
  149.  
  150.       CCCChhhhaaaannnnggggiiiinnnngggg tttthhhheeee ddddeeeeffffaaaauuuulllltttt mmmmeeeessssssssaaaaggggeeee
  151.  
  152.       By default, the software error message is followed by    a note
  153.       to contact the Webmaster by e-mail with the time and date of
  154.       the error.  If this message is not to    your liking, you can
  155.       change it using the _s_e_t__m_e_s_s_a_g_e() routine.  This is not
  156.       imported by default; you should import it on the _u_s_e() line:
  157.  
  158.           use CGI::Carp qw(fatalsToBrowser set_message);
  159.           set_message("It's    not a bug, it's    a feature!");
  160.  
  161.       You may also pass in a code reference    in order to create a
  162.       custom error message.     At run    time, your code    will be    called
  163.       with the text    of the error message that caused the script to
  164.       die.    Example:
  165.  
  166.           use CGI::Carp qw(fatalsToBrowser set_message);
  167.           BEGIN {
  168.          sub handle_errors {
  169.             my $msg = shift;
  170.             print "<h1>Oh gosh</h1>";
  171.             print "Got an error: $msg";
  172.         }
  173.         set_message(\&handle_errors);
  174.           }
  175.  
  176.       In order to correctly    intercept compile-time errors, you
  177.       should call _s_e_t__m_e_s_s_a_g_e() from within    a BEGIN{} block.
  178.  
  179.      CCCCHHHHAAAANNNNGGGGEEEE LLLLOOOOGGGG
  180.       1.05 _c_a_r_p_o_u_t() added and minor corrections by    Marc Hedlund
  181.            <hedlund@best.com> on 11/26/95.
  182.  
  183.       1.06 _f_a_t_a_l_s_T_o_B_r_o_w_s_e_r() no longer aborts for fatal errors
  184.       within
  185.            _e_v_a_l() statements.
  186.  
  187.       1.08 _s_e_t__m_e_s_s_a_g_e() added and _c_a_r_p_o_u_t() expanded to allow for
  188.       FileHandle
  189.            objects.
  190.  
  191.       1.09 _s_e_t__m_e_s_s_a_g_e() now allows    users to pass a    code REFERENCE
  192.  
  193.  
  194.  
  195.      Page 3                        (printed 10/23/98)
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.      CCCCGGGGIIII::::::::CCCCaaaarrrrpppp((((3333))))    22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))      CCCCGGGGIIII::::::::CCCCaaaarrrrpppp((((3333))))
  203.  
  204.  
  205.  
  206.       for
  207.            really custom error messages.  croak and    carp are now
  208.            exported    by default.  Thanks to Gunther Birznieks for
  209.       the
  210.            patches.
  211.  
  212.       1.10 Patch from Chris    Dean (ctdean@cogit.com)    to allow
  213.            module to run correctly under mod_perl.
  214.  
  215.      AAAAUUUUTTTTHHHHOOOORRRRSSSS
  216.       Lincoln D. Stein <lstein@genome.wi.mit.edu>.    Feel free to
  217.       redistribute this under the Perl Artistic License.
  218.  
  219.      SSSSEEEEEEEE AAAALLLLSSSSOOOO
  220.       Carp,    CGI::Base, CGI::BasePlus, CGI::Request,    CGI::MiniSvr,
  221.       CGI::Form, CGI::Response
  222.  
  223.  
  224.  
  225.  
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.      Page 4                        (printed 10/23/98)
  262.  
  263.  
  264.  
  265.